home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / AppleSearch / Windows / AppleSearch for Windows SDK / H / TCLOCK.H < prev    next >
Encoding:
C/C++ Source or Header  |  1995-11-25  |  17.3 KB  |  440 lines  |  [TEXT/dosa]
  1. /*==============================================================================
  2.     File: TCLOCK.H
  3.  
  4.     Copyright (C) 1994-1995 Apple Computer, Inc.  All rights reserved.
  5.  
  6.     Description:
  7.  
  8.         This file contains the declaration of TClock, a class that implements
  9.         calendar time in a platform-independent fashion.
  10.  
  11.         Class TClock is the central place where time related functionality is
  12.         defined for Dark Passage and its customers.
  13.  
  14.     Change History: (see the bottom of the file).
  15. ==============================================================================*/
  16.  
  17. #ifndef TCLOCK_H
  18. #define TCLOCK_H
  19.  
  20.  
  21. //==============================================================================
  22. // Macros
  23. //==============================================================================
  24.  
  25. #if !defined(MACCODE)
  26.     #ifdef WINDOWS
  27.         #define MACCODE(x)
  28.         #define WINCODE(x)    x
  29.     #else  // MACINTOSH
  30.         #define MACCODE(x)    x
  31.         #define WINCODE(x)
  32.     #endif
  33. #endif
  34.  
  35.  
  36. //==============================================================================
  37. // Dependencies
  38. //==============================================================================
  39.  
  40. #include "time.h"
  41. #if defined(MACINTOSH)
  42.     #include <OSUtils.h>
  43.     #include <types.h>
  44. #else
  45.     #include "wtypes.h"
  46. #endif
  47.  
  48.  
  49. //==============================================================================
  50. // Type Definitions
  51. //==============================================================================
  52.  
  53. typedef time_t                 ClockTicks;
  54. typedef ClockTicks        ASDate;
  55. typedef ClockTicks        ASTime;
  56. typedef ClockTicks        ASTimestamp;
  57. typedef ClockTicks        ServerTime;
  58. typedef ClockTicks        ClientTime;
  59.  
  60.  
  61. //==============================================================================
  62. // Constants
  63. //==============================================================================
  64.  
  65. const ClockTicks     kClockTicksPerSec         = (ClockTicks)CLK_TCK;
  66. const ClockTicks    kClockTicksPerMin         = kClockTicksPerSec * 60;
  67. const ClockTicks    kClockTicksPerHalfHour     = kClockTicksPerMin * 30;
  68. const ClockTicks    kClockTicksPerHour         = kClockTicksPerMin * 60;
  69.  
  70. //
  71. //    The following constants are used by function
  72. //    TClock::ClientTimeDeltaIs(CalendarBasis) to establish the appropriate
  73. //    time delta for the client's time library.  See explanation
  74. // below in class.
  75. //
  76. enum CalendarBasis
  77. {
  78.     Origin_1Jan1900,         // e.g., Microsoft Class CTime
  79.     Origin_1Jan1901,        // e.g., Borland Class TTime
  80.  
  81. };
  82.  
  83. //==============================================================================
  84. // Class TClock
  85. //
  86. //    Class TClock is the central place where time related functionality is
  87. //    defined.
  88. //==============================================================================
  89.  
  90. #ifdef __cplusplus
  91.  
  92. class TClock
  93. {
  94. //
  95. // Class Features
  96. //
  97.  
  98. public:
  99.  
  100.     //
  101.     //    class initialization
  102.     //
  103.     WINCODE(static void pascal TClockPrep(void);)
  104.     MACCODE(static pascal void TClockPrep(void);)
  105.  
  106.     // converting to clock ticks
  107.  
  108.     WINCODE(static ClockTicks pascal SecsToClockTicks(unsigned long secs);)
  109.     MACCODE(static pascal ClockTicks SecsToClockTicks(unsigned long secs);)
  110.     WINCODE(static ClockTicks pascal MinsToClockTicks(unsigned long mins);)
  111.     MACCODE(static pascal ClockTicks MinsToClockTicks(unsigned long mins);)
  112.  
  113.     // converting from clock ticks.  The second or minute, as
  114.     // appropriate, that the passed clockTicks appears in is
  115.     // returned
  116.  
  117.     WINCODE(static ClientTime pascal    ClockTicksToSecs(ClockTicks ticks);)
  118.     MACCODE(static pascal ClientTime ClockTicksToSecs(ClockTicks ticks);)
  119.     WINCODE(static unsigned long pascal ClockTicksToMinutes(ClockTicks ticks);)
  120.     MACCODE(static pascal unsigned long    ClockTicksToMinutes(ClockTicks ticks);)
  121.  
  122.     // accessing the current time since boot
  123.  
  124.     WINCODE(static ClockTicks pascal    TicksNow(void); )
  125.     MACCODE(static pascal ClockTicks TicksNow(void); )
  126.  
  127.     // Calendar Time in Dark Passage
  128.     //
  129.     //    The use of calendar time by Dark Passage must be carefully understood
  130.     // by the Dark Passage customer.  In general, Dark Passage works only with
  131.     //    calendar time systems that can express time as nnnn seconds from some
  132.     // base date.  Unfortunately for all of us, every vendor offers one or more
  133.     // calendar time packages that are based upon different dates.  For example,
  134.     //    on the PC, both the Microsoft and Borland compiler packages offer the
  135.     //    ANSI time.h library and header, both based upon 1-Jan-1970.  Microsoft
  136.     //    also offers a CTime class in their C++ package, based upon 1-Jan-1900.
  137.     // Borland offers TTime class based upon 1-Jan-1901.  On the Macintosh,
  138.     //    the ANSI time.h library is available, but based upon 1-Jan-1904.
  139.     //    Alternatively, one can use toolbox functions supplied in the rom (i.e.,
  140.     //    GetDateTime(), IUTimeString(), IUDateString(), et al), also based upon
  141.     //    1-Jan-1904.
  142.     //
  143.     //    To deal with this milieux, Dark Passage uses calendar time as follows.
  144.     //    For a given Dark Passage client (whether pc or mac based), there are
  145.     //    two kinds of calendar time being manipulated:
  146.     //
  147.     //    1)    Client Time
  148.     //        Client time is the calendar time system that the customer is using.
  149.     //        Typically, the client software is using one of the calendar time
  150.     //        manipulation packages available from the compiler and os manufacturers.
  151.     //        Since Dark Passage is itself a user of calendar time, it internally
  152.     //        manages its client time, based upon platform, as follows:
  153.     //
  154.     //         -    Mac clients use the Macintosh Toolbox, which uses seconds since
  155.     //            1-Jan-1904.
  156.     //        -    PC clients are based upon time.h, which uses seconds since 1-Jan-1970.
  157.     //
  158.     //        If the client of Dark Passage happens to use the same calendar time
  159.     //        system as Dark Passage, or is willing to express dates in these time
  160.     //        schemes when interacting with Dark Passage, nothing needs to be done.
  161.     //
  162.     //        However, it may be that the Dark Passage customer is already
  163.     //        using a time package in their application that uses another calendar
  164.     //        time basis.  This may be done, but to do so, the TClock package must be
  165.     //        initialized before it is used with the following information:
  166.     //
  167.     //        -    The difference in seconds between their calendar time bases and
  168.     //            the one used by Dark Passage internally (either 1-Jan-1904 or
  169.     //            1-Jan-1970, depending upon mac or pc client).
  170.     //
  171.     //        -    A flag set TRUE if the base time of the client's package is BEFORE
  172.     //            the Dark Passage client time, or FALSE if the client time used in
  173.     //            the Dark Passage client's time package is AFTER the Dark Passage
  174.     //            client time.
  175.     //
  176.     //        The function InitClientTimeDelta(long,Boolean) is supplied for this
  177.     //        purpose.  With it, the number of seconds and flag are explicitly set
  178.     //        before the TClock functions are needed.  As defaults, the value of
  179.     //        seconds delta value is 0 and the Boolean flag is TRUE.
  180.     //
  181.     //        In addition, an initialization function is also available that sets
  182.     //        the time delta for the commonly used calendar time libraries.
  183.     //        See ClientTimeDeltaIs(CalendarBasis) for more details. This function
  184.     //        may be used in lieu of the InitClientTimeDelta(long,Boolean) function,
  185.     //        if    appropriate.
  186.     //
  187.     //        Use typedef ClientTime when declaring or casting client time variables
  188.     //        and expressions.
  189.     //
  190.     //    2) Server Time (use typedef ServerTime)
  191.     //        Server time is based upon the seconds +/- 12:00:00 AM, 1-Jan-2000.
  192.     //        With the current implementation, the earliest expressable time is
  193.     //        2:05:52 AM, 11-June-1934.  The latest expressable server time
  194.     //        is 6:28:15 AM, 6-February-2040.
  195.     //
  196.     //        Use typedef ServerTime when declaring or casting client time variables
  197.     //        and expressions.
  198.     //
  199.  
  200.     //
  201.     //    Client delta initialization (see explanation of calendar time above)
  202.     //
  203.  
  204.     MACCODE(static pascal void InitClientTimeDelta(long delta,Boolean isEarlier);)
  205.     MACCODE(static pascal Boolean ClientTimeDeltaIs(CalendarBasis aTimePkgBaseTm);)
  206.     WINCODE(static void pascal InitClientTimeDelta(long delta,Boolean isEarlier);)
  207.     WINCODE(static Boolean pascal ClientTimeDeltaIs(CalendarBasis aTimePkgBaseTm);)
  208.  
  209.     //
  210.     //    ClientTime<->ServerTime Conversion functions
  211.     //
  212.  
  213.     MACCODE(static pascal ServerTime    ClientTimeToServerTime(ClientTime theClientTime);)
  214.     MACCODE(static pascal ClientTime    ServerTimeToClientTime(ServerTime theServerTime);)
  215.     WINCODE(static ServerTime pascal ClientTimeToServerTime(ClientTime theClientTime);)
  216.     WINCODE(static ClientTime pascal    ServerTimeToClientTime(ServerTime theServerTime);)
  217.  
  218.     //
  219.     //    Date<->Seconds Conversions
  220.     //
  221.  
  222.     MACCODE(static pascal void    DateToSeconds(DateTimeRec *theDT, ClientTime *seconds);)
  223.     MACCODE(static pascal void    SecondsToDate(ClientTime seconds,DateTimeRec *theDT);)
  224.     WINCODE(static void pascal    DateToSeconds(struct tm *theDT, ClientTime *seconds);)
  225.     WINCODE(static void pascal    SecondsToDate(ClientTime seconds, struct tm *theDT);)
  226.  
  227.     //
  228.     //    struct tm -> struct DateTimeRec conversion
  229.     //
  230.     //    This routine move the corresponding fields from one structure to the
  231.     //    other, adjusting them from a zero-base to a one-base as appropriate
  232.     //    (e.g., when tm_mon = 0 it is jan; when month=1 in a DateTimeRec, it is
  233.     //    jan).
  234.     //
  235.     //    Its purpose is to simplify the porting of mac code to the pc that is
  236.     //    heavily based upon DateTimeRec. A good example is the
  237.     //    TPboyDeliveryTime::TimeToDeliver() method.
  238.     //
  239.     WINCODE(static void pascal StructTMToDateTimeRec(struct tm *ansiTm,DateTimeRec *macTm);)
  240.     MACCODE(static pascal void StructTMToDateTimeRec(struct tm *ansiTm,DateTimeRec *macTm);)
  241.  
  242.     //
  243.     //    Date and Time -> String Conversions
  244.     //
  245.     //    A pascal string is formatted in buff. At buff + 1, a c string is
  246.     //    available.  A buffer of at least FORMAT_BUFFER_SZ is expected.
  247.     //
  248.     enum
  249.     {
  250.         FORMAT_BUFFER_SZ = 256,
  251.     };
  252.     MACCODE(static pascal void FormatTime(ClientTime seconds,Boolean wantSecs,StringPtr buff);)
  253.     MACCODE(static pascal void FormatDate(ClientTime seconds,DateForm format,StringPtr buff);)
  254.     WINCODE(static void pascal FormatTime(ClientTime seconds,Boolean wantSecs,StringPtr buff);)
  255.     WINCODE(static void pascal FormatDate(ClientTime seconds,DateForm format,StringPtr buff);)
  256.  
  257.     //
  258.     //    Generalized Date and Time formatting
  259.     //
  260.     //    Use the passed format string to format the passed client time in the supplied
  261.     // buffer.  Formatting characters are the same as those used by the ansi time.h
  262.     // function, strftime().  See your compiler's run-time documentation for
  263.     //    details.  As above, a pascal string is formatted in buff. At buff + 1, a
  264.     //    c string is available.  A buffer of at least FORMAT_BUFFER_SZ is expected.
  265.     //
  266.     MACCODE(static pascal void FormatDateTime(ClientTime seconds,char* format,StringPtr buff);)
  267.     WINCODE(static void pascal FormatDateTime(ClientTime seconds,char* format,StringPtr buff);)
  268.  
  269.     //
  270.     //    Access current client calendar time, expressed in seconds since the
  271.     //    base time (platform and compiler dependent value).
  272.     //
  273.  
  274.     MACCODE(static pascal void CurrentTime(ClientTime *inSeconds);)
  275.     WINCODE(static void pascal CurrentTime(ClientTime *inSeconds);)
  276.  
  277.     //
  278.     //    Time Style determination
  279.     //
  280.     //    Determine whether calendar time should be formatted in a Euro-style
  281.     //    (e.g., 12Feb1904 or variant) or according to the US style.  Determination
  282.     //    based upon the appropriate system 'gestalt' methods
  283.     //
  284.     MACCODE(static pascal Boolean EuroTimeStyle();)
  285.     WINCODE(static Boolean pascal EuroTimeStyle();)
  286.     MACCODE(static pascal Boolean USEnglishTimeStyle();)
  287.     WINCODE(static Boolean pascal USEnglishTimeStyle();)
  288.  
  289.     //
  290.     // Time comparison functions
  291.     //
  292.  
  293.     // Determine if both times are in same minute of same hour of same day of same
  294.     // month of same year.
  295.     MACCODE(static pascal Boolean InSameMinute(ClientTime t1, ClientTime t2);)
  296.     WINCODE(static Boolean pascal InSameMinute(ClientTime t1, ClientTime t2);)
  297.  
  298.     //
  299.     // Instance Features
  300.     //
  301.  
  302.         // (none)
  303. };
  304.  
  305. //==============================================================================
  306. // TClock inline function implementations
  307. //==============================================================================
  308.  
  309. //------------------------------------------------------------------------------
  310. // SecsToClockTicks(secs)
  311. //------------------------------------------------------------------------------
  312.  
  313. WINCODE(inline ClockTicks _export pascal TClock::SecsToClockTicks(unsigned long secs))
  314. MACCODE(inline pascal ClockTicks TClock::SecsToClockTicks(unsigned long secs))
  315. {
  316.     return (secs * kClockTicksPerSec);
  317. }
  318.  
  319. //------------------------------------------------------------------------------
  320. // MinsToClockTicks(secs)
  321. //------------------------------------------------------------------------------
  322.  
  323. WINCODE(inline ClockTicks _export pascal TClock::MinsToClockTicks(unsigned long mins))
  324. MACCODE(inline pascal ClockTicks TClock::MinsToClockTicks(unsigned long mins))
  325. {
  326.     return (mins * kClockTicksPerMin);
  327. }
  328.  
  329. //------------------------------------------------------------------------------
  330. // TicksNow()
  331. //
  332. // Description:
  333. //         Answer the current system time expressed as the number of clock ticks
  334. //            since the system was last started.
  335. //------------------------------------------------------------------------------
  336.  
  337. WINCODE(inline ClockTicks _export pascal TClock::TicksNow())
  338. MACCODE(inline pascal ClockTicks TClock::TicksNow())
  339. {
  340.     WINCODE(return ((ClockTicks)clock());)
  341.     MACCODE(return ((ClockTicks)TickCount());)
  342. }
  343. #endif    // __cplusplus
  344.  
  345. //==============================================================================
  346. //
  347. //    C API versions of the TClock functions.
  348. //
  349. //    See the documentation in the class above for the semantics of these functions.
  350. //
  351. //==============================================================================
  352. #ifdef __cplusplus
  353. extern "C"
  354. {
  355. #endif
  356.     //    initialization
  357.     WINCODE(void _export pascal ASClockPrep(void);)
  358.     MACCODE(pascal void ASClockPrep(void);)
  359.  
  360.     // converting to clock ticks
  361.     WINCODE(ClockTicks _export pascal ASSecsToClockTicks(unsigned long secs);)
  362.     MACCODE(pascal ClockTicks ASSecsToClockTicks(unsigned long secs);)
  363.     WINCODE(ClockTicks _export pascal ASMinsToClockTicks(unsigned long mins);)
  364.     MACCODE(pascal ClockTicks ASMinsToClockTicks(unsigned long mins);)
  365.  
  366.     // converting from clock ticks
  367.     WINCODE(ClientTime _export pascal        ASClockTicksToSecs(ClockTicks ticks);)
  368.     MACCODE(pascal ClientTime         ASClockTicksToSecs(ClockTicks ticks);)
  369.     WINCODE(unsigned _export long pascal     ASClockTicksToMinutes(ClockTicks ticks);)
  370.     MACCODE(pascal unsigned long    ASClockTicksToMinutes(ClockTicks ticks);)
  371.  
  372.     // accessing the current time since boot
  373.     WINCODE(ClockTicks _export pascal    ASTicksNow(void); )
  374.     MACCODE(pascal ClockTicks     ASTicksNow(void); )
  375.  
  376.     //    Client delta initialization (see explanation of calendar time above)
  377.     MACCODE(pascal void         ASInitClientTimeDelta(long delta,Boolean isEarlier);)
  378.     MACCODE(pascal Boolean     ASClientTimeDeltaIs(CalendarBasis aTimePkgBaseTm);)
  379.     WINCODE(void _export pascal         ASInitClientTimeDelta(long delta,Boolean isEarlier);)
  380.     WINCODE(Boolean _export pascal     ASClientTimeDeltaIs(CalendarBasis aTimePkgBaseTm);)
  381.  
  382.     //    ClientTime<->ServerTime Conversion functions
  383.     MACCODE(pascal ServerTime    ASClientTimeToServerTime(ClientTime theClientTime);)
  384.     MACCODE(pascal ClientTime    ASServerTimeToClientTime(ServerTime theServerTime);)
  385.     WINCODE(ServerTime _export pascal     ASClientTimeToServerTime(ClientTime theClientTime);)
  386.     WINCODE(ClientTime _export pascal    ASServerTimeToClientTime(ServerTime theServerTime);)
  387.  
  388.     //    Date<->Seconds Conversions
  389.     MACCODE(pascal void    ASDateToSeconds(DateTimeRec *theDT, ClientTime *seconds);)
  390.     MACCODE(pascal void    ASSecondsToDate(ClientTime seconds,DateTimeRec *theDT);)
  391.     WINCODE(void _export pascal    ASDateToSeconds(struct tm *theDT, ClientTime *seconds);)
  392.     WINCODE(void _export pascal    ASSecondsToDate(ClientTime seconds, struct tm *theDT);)
  393.  
  394.     //    struct tm -> struct DateTimeRec conversion
  395.     WINCODE(void _export pascal ASStructTMToDateTimeRec(struct tm *ansiTm,DateTimeRec *macTm);)
  396.     MACCODE(pascal void ASStructTMToDateTimeRec(struct tm *ansiTm,DateTimeRec *macTm);)
  397.  
  398.     //    Date and Time -> String Conversions
  399.     MACCODE(pascal void ASFormatTime(ClientTime seconds,Boolean wantSecs,StringPtr buff);)
  400.     MACCODE(pascal void ASFormatDate(ClientTime seconds,DateForm format,StringPtr buff);)
  401.     WINCODE(void _export pascal ASFormatTime(ClientTime seconds,Boolean wantSecs,StringPtr buff);)
  402.     WINCODE(void _export pascal ASFormatDate(ClientTime seconds,DateForm format,StringPtr buff);)
  403.  
  404.     //    Generalized Date and Time formatting
  405.     MACCODE(pascal void ASFormatDateTime(ClientTime seconds,char* format,StringPtr buff);)
  406.     WINCODE(void _export pascal ASFormatDateTime(ClientTime seconds,char* format,StringPtr buff);)
  407.  
  408.     //    Access current client calendar time
  409.     MACCODE(pascal void ASCurrentTime(ClientTime *inSeconds);)
  410.     WINCODE(void _export pascal ASCurrentTime(ClientTime *inSeconds);)
  411.  
  412.     //    Time Style determination
  413.     MACCODE(pascal Boolean ASEuroTimeStyle();)
  414.     WINCODE(Boolean _export pascal ASEuroTimeStyle();)
  415.     MACCODE(pascal Boolean ASUSEnglishTimeStyle();)
  416.     WINCODE(Boolean _export pascal ASUSEnglishTimeStyle();)
  417.  
  418.     // Calendar time comparisons
  419.     MACCODE(pascal Boolean ASInSameMinute(ClientTime t1, ClientTime t2);)
  420.     WINCODE(Boolean pascal ASInSameMinute(ClientTime t1, ClientTime t2);)
  421.  
  422. #ifdef __cplusplus
  423. }
  424. #endif
  425.  
  426. #endif // TCLOCK_H
  427.  
  428.  
  429. //    Change History: (prior to cut over to source safe based log)
  430. //
  431. //        Date        By        Description
  432. //        ----        --        -----------
  433. //        03/23/94    SW        Added kClockTicksPerHalfHour and kClockTicksPerHour.
  434. //
  435. // $Log: /bogart/dp/shared/TCLOCK.H $
  436. // 
  437. // 9     12/21/94 7:37p Rich_johnson
  438. //
  439.  
  440.